// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 用于测量运行时间的简单秒表。
 */
class Stopwatch {
  /**
   * 计时器的频率，单位为Hz（赫兹）。
   */
  int get frequency => _frequency;

  // The _start and _stop fields capture the time when [start] and [stop]
  // are called respectively.
  // If _start is null, then the [Stopwatch] has not been started yet.
  // If _stop is null, then the [Stopwatch] has not been stopped yet,
  // or is running.
  int _start;
  int _stop;

  /**
   * 在停止状态， 创建一个运行时间为0的[Stopwatch]对象。
   *
   * 下面的代码演示如何在分配之后立即启动[Stopwatch]。
   *
   *     Stopwatch stopwatch = new Stopwatch()..start();
   */
  Stopwatch() {
    _initTicker();
  }

  /**
   * 开始计时。
   *
   *
   * 运行时间[elapsed]是单调递增的。
   * 如果[Stopwatch]停止，然后再次调用start时，并不会重置[elapsed]。
   *
   * 如果[Stopwatch]正在运行，那么调用start不会执行任何操作。
   */
  void start() {
    if (isRunning) return;
    if (_start == null) {
      // This stopwatch has never been started.
      _start = _now();
    } else {
      // Restart this stopwatch. Prepend the elapsed time to the current
      // start time.
      _start = _now() - (_stop - _start);
      _stop = null;
    }
  }

  /**
   * 停止计时。
   *
   * 调用该方法后，时钟数[elapsedTicks]停止递增。
   * 如果[Stopwatch]当前并没有运行，那么调用stop不会执行任何操作。
   */
  void stop() {
    if (!isRunning) return;
    _stop = _now();
  }

  /**
   * 重置运行时间[elapsed]为0。
   *
   * 这个方法并不会停止或启动[Stopwatch]。
   */
  void reset() {
    if (_start == null) return;
    // If [_start] is not null, then the stopwatch had already been started. It
    // may running right now.
    _start = _now();
    if (_stop != null) {
      // The watch is not running. So simply set the [_stop] to [_start] thus
      // having an elapsed time of 0.
      _stop = _start;
    }
  }

  /**
   * 返回调用[start]以来运行的时钟数，尽管[Stopwatch]正在运行。
   *
   * 返回调用[start]和[stop]之间运行的时钟数。
   * 如果[Stopwatch]还没有启动的话，返回0。
   *
   * 运行的时钟数每秒以[frequency]为频率递增。
   */
  int get elapsedTicks {
    if (_start == null) {
      return 0;
    }
    return (_stop == null) ? (_now() - _start) : (_stop - _start);
  }

  /**
   * 将运行的时钟数[elapsedTicks]转换成[Duration]，并返回。
   */
  Duration get elapsed {
    return new Duration(microseconds: elapsedMicroseconds);
  }

  /**
   * 将运行的时钟数[elapsedTicks]转换成微秒，并返回。
   */
  int get elapsedMicroseconds {
    return (elapsedTicks * 1000000) ~/ frequency;
  }

  /**
   * 将运行的时钟数[elapsedTicks]转换成毫秒，并返回。
   */
  int get elapsedMilliseconds {
    return (elapsedTicks * 1000) ~/ frequency;
  }


  /**
   * [StopWatch]是否正在运行。
   */
  bool get isRunning => _start != null && _stop == null;

  /**
   * Cached frequency of the system. Must be initialized in [_initTicker];
   */
  static int _frequency;

  /**
   * Initializes the time-measuring system. *Must* initialize the [_frequency]
   * variable.
   */
  external static void _initTicker();
  external static int _now();
}
